Loan Management APIs

These endpoints cover loan disbursement, payment recording, and live loan account status.

Authentication

All requests require:

Authorization: Bearer demo-credify-token

4. Loan Disbursement

Endpoint

POST /api/v1/loans/{loan_id}/disburse

Description

Register a loan disbursement and generate a transaction reference.

Sample request

{
  "merchant_bank_account": "EG380019000500000000263180002",
  "disbursement_amount": 32000.0,
  "disbursement_date": "2026-04-24",
  "disbursement_method": "bank_transfer"
}

Sample response

{
  "loan_id": "LN-2026-001",
  "merchant_bank_account": "EG380019000500000000263180002",
  "disbursement_amount": 32000.0,
  "disbursement_date": "2026-04-24",
  "disbursement_method": "bank_transfer",
  "disbursement_reference": "DISB-LN-2026-001-002",
  "status": "completed"
}

Field	Type	Direction	Description
loan_id	string	Request	Target loan account
merchant_bank_account	string	Request	Receiving account
disbursement_amount	decimal	Request	Amount to send
disbursement_date	date	Request	Scheduled disbursement date
disbursement_method	enum	Request	bank_transfer, wallet, check
disbursement_reference	string	Response	Generated transfer reference
status	enum	Response	pending, completed, failed

5. Record Repayment

Endpoint

POST /api/v1/loans/{loan_id}/payments

Description

Record a repayment and automatically split the amount into principal and interest.

Sample request

{
  "payment_amount": 5200.0,
  "payment_date": "2026-05-30",
  "payment_method": "auto_debit"
}

Sample response

{
  "loan_id": "LN-2026-001",
  "payment_amount": 5200.0,
  "payment_date": "2026-05-30",
  "payment_method": "auto_debit",
  "principal_amount": 4823.3,
  "interest_amount": 376.7,
  "remaining_balance": 21382.03
}

Field	Type	Direction	Description
loan_id	string	Request	Loan account reference
payment_amount	decimal	Request	Amount received
payment_date	date	Request	Payment booking date
payment_method	enum	Request	auto_debit, manual_transfer, revenue_share
principal_amount	decimal	Response	Applied to principal
interest_amount	decimal	Response	Applied to interest
remaining_balance	decimal	Response	Balance after posting

6. Loan Account Status

Endpoint

GET /api/v1/loans/{loan_id}

Description

Return the live loan account summary with payment history and next due date.

Sample response

{
  "loan_id": "LN-2026-001",
  "merchant_id": "MCH-22346",
  "original_amount": 32000.0,
  "outstanding_balance": 26205.33,
  "next_payment_due_date": "2026-05-18",
  "payment_status": "current",
  "total_payments_made": 2,
  "currency": "EGP",
  "business_name": "Nile Home Goods",
  "interest_rate": 17.25,
  "term_months": 10,
  "disbursement_status": "completed"
}

Field	Type	Description
loan_id	string	Unique loan identifier
merchant_id	string	Associated merchant
original_amount	decimal	Initial approved principal
outstanding_balance	decimal	Current balance owed
next_payment_due_date	date	Next scheduled due date
payment_status	enum	current, overdue, paid_off, defaulted
total_payments_made	integer	Number of recorded payments
currency	string	Merchant currency, fixed to EGP in this demo
business_name	string	Merchant legal name
interest_rate	decimal	APR applied to the loan
term_months	integer	Loan duration
disbursement_status	enum	Late